docs(inbox): flag default state= excludes acked/expired for conversation-view consumers#99
Merged
Conversation
…ion-view consumers
Add a Conversation-view consumer note to GET /v1/agents/{ref}/inbox
explaining that the default state filter excludes `acked` + `expired`,
which is right for worker-runtime/agent-handler consumers but wrong
for chat UIs / message-thread renderers / audit logs.
## Why
Empirical: 2026-05-21, Dock's cue.dock.svc /api/threads consumer hit
the asymmetry. Recipient pane was empty for cross-user messages
because Dock's own desktop worker poll-acked them faster than the
human-facing /api/threads could surface them. Sent-side bubbles
rendered correctly because Dock's sent view requested all states.
Substrate behavior is correct — messages WERE delivered + acked.
Dock fixed Dock-side by passing the full state set on the threads
fetch. But any future conversation-view consumer will hit the same
trap unless flagged in the docs.
## What changed
- `state=` parameter description: expanded from one-liner to call
out the worker-default-vs-conversation-view distinction + give
the exact state-set string conversation consumers should pass
- Added "Conversation-view consumer note (v1.1.5 docs)" section to
the endpoint docstring with the empirical Dock anchor
No code change. Docs only. Per Mike directive 2026-05-21 ~22:48Z
"in general we need to do 5x better on documentation."
Backlog row: cmpg2szip000404l4ibldaq6e
Jingim DX note: msg_q8zsi74xe4us
Parity checkThis PR modifies files tracked in
Please confirm one of the following in a reply or PR description update:
This is a soft check — it does not block merge. The goal is visibility, not friction. See HOSTED_ONLY.md for the open-core policy. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only fix for
GET /v1/agents/{ref}/inbox. Flags that the defaultstate=filter excludesacked+expired(correct for worker-runtime consumers; wrong for conversation/transcript consumers like chat UIs).Why
Empirical (2026-05-21, msg_q8zsi74xe4us): Dock's
cue.dock.svc /api/threadsconsumer hit the asymmetry. Cross-user messages were ack'd by Dock's own desktop worker faster than the human-facing/api/threadscould surface them → recipient pane empty while sender bubbles rendered correctly (sent-side requested all states; inbox-side took the default).Substrate behavior is correct — messages were delivered + acked successfully. Dock fixed Dock-side. But any future conversation-view consumer hits the same trap without docs flagging.
Mike directive 2026-05-21 ~22:48Z (via cue-pm): "in general we need to do 5x better on documentation of all of our code we write and features we make b/c right now, our documentation is severely lacking." This is the first instance.
Changes
app/routers/agents.py— expandedstate=Query description + added "Conversation-view consumer note" section in the endpoint docstring with Jingim's suggested phrasing + the exact state-set string conversation consumers should pass + empirical Dock anchorNo code change. Docs only.
Test plan
pytest tests/test_agents.py -q→ 22/22 pass (no regression)python3 -c "import ast; ast.parse(open('app/routers/agents.py').read())"→ syntax OKNo canary needed (docs-only). No G14 prod-verify needed (docs don't affect runtime behavior).
Cross-refs
cmpg2szip000404l4ibldaq6e🤖 Generated with Claude Code